Skip to main content

API Design (REST) — Detailed Learning Notes

1. Introduction to API Design​

  • API design is a core responsibility of backend engineers

  • Focus of this discussion: REST APIs

  • Other API styles exist:

    • RPC
    • GraphQL

  • Goal:

    • Create consistent, standardized APIs

    • Avoid confusion over:

      • URI naming
      • HTTP methods
      • Status codes

  • Emphasis: Follow existing standards, not invent new ones

2. Common API Design Confusions​

  • Should endpoints be:

    • /book vs /books?

  • When updating:

    • PUT vs PATCH?

  • For custom actions:

    • Which HTTP method?

  • What status codes to use?

  • These issues arise because:

    • Standards were designed during MPA era
    • Today we use SPA (Single Page Applications)

3. Goal of API Design Guidelines​

  • Extract rules from REST standards

  • Ensure:

    • Consistency
    • Predictability

  • Benefit:

    • Focus shifts to business logic instead of conventions

4. History of REST​

4.1 Origin of the Web​

  • 1990: Tim Berners-Lee created:

    • URI
    • HTTP
    • HTML
    • First browser & server

  • Purpose:

    • Share knowledge globally

4.2 Scaling Problem​

  • Rapid growth → web couldn’t scale

  • Needed:

    • New architectural constraints

4.3 Contribution of Roy Fielding​

  • Proposed constraints to solve scalability
  • Later defined REST architecture (2000)
  • Basis of modern API design

5. REST Constraints​

5.1 Client-Server​

  • Separation of concerns:

    • Client → UI
    • Server → data + logic

  • Enables independent scaling

5.2 Uniform Interface​

  • Standardized communication

  • Sub-components:

    • Resource identification
    • Representation-based manipulation
    • Self-descriptive messages
    • HATEOAS

5.3 Layered System​

  • Architecture is layered:

    • Client → Load Balancer → Server → DB

  • Improves:

    • Scalability
    • Security

5.4 Caching​

  • Responses must define:

    • Cacheable / non-cacheable

  • Benefits:

    • Reduced server load
    • Faster responses

5.5 Statelessness​

  • Each request must contain:

    • All required data

  • Server does NOT remember past requests

  • Enables:

    • Horizontal scaling
    • Load balancing

5.6 Code on Demand (Optional)​

  • Server can send executable code (e.g., JS)

6. What is REST? (Meaning)​

REST = Representational State Transfer​

6.1 Representation​

  • Resources are represented in formats:

    • JSON (most common)
    • HTML
    • XML

6.2 State​

  • Resource’s current data

  • Example:

    • Cart → items, quantity, price

6.3 Transfer​

  • Data exchanged via:

    • HTTP methods (GET, POST, etc.)

Final Meaning​

  • System where:

    • Resources have representations
    • State is transferred via HTTP
    • Follows REST constraints

7. URL Structure​

General Format​

scheme://domain/path?query#fragment

Components​

  • Scheme → http, https
  • Domain → example.com
  • Path → resource
  • Query → filters
  • Fragment → page section

8. API URL Design​

Standard Structure​

https://api.example.com/v1/resource

Breakdown​

  • https → secure protocol
  • api. → subdomain
  • /v1 → versioning
  • /resource → endpoint

9. Resource Naming Rules​

Rule 1: Use Plural​

  • Correct:

    • /books

  • Incorrect:

    • /book

Even for Single Resource​

  • Correct:

    • /books/1

  • Not:

    • /book/1

Reason​

  • Path represents collection, not instance

10. Hierarchical Paths​

  • /books/1 means:

    • books → collection
    • 1 → specific item

11. URL Best Practices​

Avoid​

  • Spaces
  • Underscores

Use​

  • Lowercase
  • Hyphens

Example​

  • "Harry Potter" → harry-potter

12. Slugs​

Definition​

  • Human-readable identifier

Example​

/books/harry-potter

Transformation Rules​

  • Lowercase
  • Replace spaces → -

13. Idempotency​

Definition​

  • Repeating request → same result

Meaning​

  • Calling API 1 time or 100 times → same effect

Example​

  • DELETE request:

    • Deleting same resource multiple times → still deleted

Importance​

  • Prevents:

    • Duplicate actions
    • Unexpected side effects

14. HTTP Methods (Intro Context)​

  • REST uses:

    • GET
    • POST
    • PUT
    • PATCH
    • DELETE

  • Each method maps to:

    • Specific action

[Context unclear – deeper mapping likely in next part]

15. Key Takeaways​

  • REST is about:

    • Standardization
    • Scalability

  • Always:

    • Use plural resources
    • Follow consistent URL structure
    • Maintain statelessness

  • API design should:

    • Be predictable
    • Be consistent
    • Reduce decision fatigue